home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 1.iso / dist / fw_cyrus-sasl.idb / usr / freeware / include / sasl.h.z / sasl.h
C/C++ Source or Header  |  2001-07-06  |  35KB  |  942 lines
  1. /* This is a proposed C API for support of SASL
  2.  *
  3.  * Basic Type Summary:
  4.  *  sasl_conn_t       Context for a SASL connection negotiation
  5.  *  sasl_ssf_t        Security layer Strength Factor
  6.  *  sasl_callback_t   A typed client/server callback function and context
  7.  *  sasl_interact_t   A client interaction descriptor
  8.  *  sasl_secret_t     A client authentication secret/credentials/passphrase
  9.  *  sasl_rand_t       Random data context structure
  10.  *  sasl_security_properties_t  An application's required security level
  11.  *  sasl_external_properties_t  Security provided by an external security layer
  12.  *
  13.  * Callbacks:
  14.  *  sasl_getopt_t     client/server: Get an option value
  15.  *  sasl_log_t        client/server: Log message handler
  16.  *  sasl_getpath_t    client/server: Get path to search for mechanisms
  17.  *  sasl_getsimple_t  client: Get user/language list
  18.  *  sasl_getsecret_t  client: Get authentication secret
  19.  *  sasl_chalprompt_t client: Display challenge and prompt for response
  20.  *  sasl_authorize_t  server: Authorize policy callback
  21.  *  sasl_server_getsecret_t server: User secret database read
  22.  *  sasl_server_putsecret_t server: User secret database write
  23.  *
  24.  * Client/Server Function Summary:
  25.  *  sasl_done         Release all SASL global state
  26.  *  sasl_dispose      Connection done: Dispose of sasl_conn_t
  27.  *  sasl_getprop      Get property (e.g., user name, security layer info)
  28.  *  sasl_setprop      Set property (e.g., external ssf)
  29.  *  sasl_usererr      Translate server error code to user error code
  30.  *  sasl_errstring    Translate sasl error code to a string
  31.  *  sasl_encode       Encode data to send using security layer
  32.  *  sasl_decode       Decode data received using security layer
  33.  *
  34.  * Client Function Summary:
  35.  *  sasl_client_init  Load and initialize client plug-ins (call once)
  36.  *  sasl_client_new   Initialize client connection context: sasl_conn_t
  37.  *  sasl_client_start Select mechanism for connection
  38.  *  sasl_client_step  Perform one authentication step
  39.  *  sasl_client_auth  Create client secret (e.g., from a user & passphrase)
  40.  *  sasl_free_secret  Erase & Dispose of a sasl_secret_t
  41.  *
  42.  * Server Function Summary
  43.  *  sasl_server_init  Load and initialize server plug-ins (call once)
  44.  *  sasl_server_new   Initialize server connection context: sasl_conn_t
  45.  *  sasl_listmech     Create list of available mechanisms
  46.  *  sasl_server_start Begin an authentication exchange
  47.  *  sasl_server_step  Perform one authentication exchange step
  48.  *  sasl_checkpass    Check a plaintext passphrase
  49.  *  sasl_userexists   Check if user exists
  50.  *  sasl_setpass      Change a password or add a user entry
  51.  *
  52.  * Basic client model:
  53.  *  1. client calls sasl_client_init() at startup to load plug-ins
  54.  *  2. when connection formed, call sasl_client_new()
  55.  *  3. once list of supported mechanisms received from server, client
  56.  *     calls sasl_client_start().  goto 4a
  57.  *  4. client calls sasl_client_step()
  58.  * [4a. If SASL_INTERACT, fill in prompts and goto 4
  59.  *      -- doesn't happen if callbacks provided]
  60.  *  4b. If SASL error, goto 7 or 3
  61.  *  4c. If SASL_OK, continue or goto 6 if last server response was success
  62.  *  5. send message to server, wait for response
  63.  *  5a. On data or success with server response, goto 4
  64.  *  5b. On failure goto 7 or 3
  65.  *  5c. On success with no server response continue
  66.  *  6. continue with application protocol until connection closes
  67.  *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
  68.  *  7. call sasl_dispose(), may return to step 2
  69.  *  8. call sasl_done() when program terminates
  70.  *
  71.  * Basic Server model:
  72.  *  1. call sasl_server_init() at startup to load plug-ins
  73.  *  2. On connection, call sasl_server_new()
  74.  * [3. call sasl_listmech() and send list to client]
  75.  *  4. after client AUTH command, call sasl_server_start(), goto 5a
  76.  *  5. call sasl_server_step()
  77.  *  5a. If SASL_CONTINUE, output to client, wait response, repeat 5
  78.  *  5b. If SASL error, then goto 7
  79.  *  5c. If SASL_OK, move on
  80.  *  6. continue with application protocol until connection closes
  81.  *     call sasl_getprop/sasl_encode/sasl_decode() if using security layer
  82.  *  7. call sasl_dispose(), may return to step 2
  83.  *  8. call sasl_done() when program terminates
  84.  *
  85.  */
  86.  
  87. #ifndef SASL_H
  88. #define SASL_H 1
  89.  
  90. #define SASL_VERSION_MAJOR 1
  91. #define SASL_VERSION_MINOR 5
  92. #define SASL_VERSION_STEP 24
  93.  
  94. /* The following ifdef block is the standard way of creating macros
  95.  * which make exporting from a DLL simpler. All files within this DLL
  96.  * are compiled with the LIBSASL_EXPORTS symbol defined on the command
  97.  * line. this symbol should not be defined on any project that uses
  98.  * this DLL. This way any other project whose source files include
  99.  * this file see LIBSASL_API functions as being imported from a DLL,
  100.  * wheras this DLL sees symbols defined with this macro as being
  101.  * exported.  */
  102. /* Under Unix, life is simpler: we just need to mark library functions
  103.  * as extern.  (Technically, we don't even have to do that.) */
  104. #ifdef WIN32
  105. # ifdef LIBSASL_EXPORTS
  106. #  define LIBSASL_API  __declspec(dllexport)
  107. # else /* LIBSASL_EXPORTS */
  108. #  define LIBSASL_API  __declspec(dllimport)
  109. # endif /* LIBSASL_EXPORTS */
  110. #else /* WIN32 */
  111. # define LIBSASL_API extern
  112. #endif /* WIN32 */
  113.  
  114. /*************
  115.  * Basic API *
  116.  *************/
  117.  
  118. /* SASL result codes: */
  119. #define SASL_CONTINUE   (1)  /* another step is needed in authentication */
  120. #define SASL_OK         (0)  /* successful result */
  121. #define SASL_FAIL      (-1)  /* generic failure */
  122. #define SASL_NOMEM     (-2)  /* memory shortage failure */
  123. #define SASL_BUFOVER   (-3)  /* overflowed buffer */
  124. #define SASL_NOMECH    (-4)  /* mechanism not supported */
  125. #define SASL_BADPROT   (-5)  /* bad protocol / cancel */
  126. #define SASL_NOTDONE   (-6)  /* can't request info until later in exchange */
  127. #define SASL_BADPARAM  (-7)  /* invalid parameter supplied */
  128. #define SASL_TRYAGAIN  (-8)  /* transient failure (e.g., weak key) */
  129. #define SASL_BADMAC    (-9)  /* integrity check failed */
  130.                              /* -- client only codes -- */
  131. #define SASL_INTERACT   (2)  /* needs user interaction */
  132. #define SASL_BADSERV   (-10) /* server failed mutual authentication step */
  133. #define SASL_WRONGMECH (-11) /* mechanism doesn't support requested feature */
  134. #define SASL_NEWSECRET (-12) /* new secret needed */
  135.                              /* -- server only codes -- */
  136. #define SASL_BADAUTH   (-13) /* authentication failure */
  137. #define SASL_NOAUTHZ   (-14) /* authorization failure */
  138. #define SASL_TOOWEAK   (-15) /* mechanism too weak for this user */
  139. #define SASL_ENCRYPT   (-16) /* encryption needed to use mechanism */
  140. #define SASL_TRANS     (-17) /* One time use of a plaintext password will
  141.                 enable requested mechanism for user */
  142. #define SASL_EXPIRED   (-18) /* passphrase expired, has to be reset */
  143. #define SASL_DISABLED  (-19) /* account disabled */
  144. #define SASL_NOUSER    (-20) /* user not found */
  145. #define SASL_PWLOCK    (-21) /* password locked */
  146. #define SASL_NOCHANGE  (-22) /* requested change was not needed */
  147. #define SASL_BADVERS   (-23) /* version mismatch with plug-in */
  148.  
  149. #define SASL_NOPATH    (-25) /* path not set */
  150.  
  151. /* max size of a sasl mechanism name */
  152. #define SASL_MECHNAMEMAX 20
  153.  
  154. /* per-connection SASL negotiation state for client or server
  155.  */
  156. typedef struct sasl_conn sasl_conn_t;
  157.  
  158. /* opaque passphrase/secret kept encrypted by API middleware
  159.  *  can be used by caller for single sign-on
  160.  * client "KEY" option will be used as key for
  161.  *  clients which offer a save-to-disk option.
  162.  */
  163. typedef struct sasl_secret {
  164.     unsigned long len;
  165.     char data[1];        /* variable sized */
  166. } sasl_secret_t;
  167.  
  168. /* random data context structure
  169.  */
  170. typedef struct sasl_rand_s sasl_rand_t;
  171.  
  172.  
  173. /****************************
  174.  * Configure Basic Services *
  175.  ****************************/
  176.  
  177. /* the following functions are used to adjust how allocation and mutexes work
  178.  * they must be called before all other SASL functions:
  179.  */
  180.  
  181. /* memory allocation functions which may optionally be replaced:
  182.  */
  183. typedef void *sasl_malloc_t(unsigned long);
  184. typedef void *sasl_calloc_t(unsigned long, unsigned long);
  185. typedef void *sasl_realloc_t(void *, unsigned long);
  186. typedef void sasl_free_t(void *);
  187.  
  188. LIBSASL_API void sasl_set_alloc(sasl_malloc_t *,
  189.                 sasl_calloc_t *,
  190.                 sasl_realloc_t *,
  191.                                 sasl_free_t *);
  192.  
  193. /* mutex functions which may optionally be replaced:
  194.  *  sasl_mutex_new allocates a mutex structure
  195.  *  sasl_mutex_lock blocks until mutex locked
  196.  *   returns SASL_FAIL on deadlock or parameter error
  197.  *   returns SASL_OK on success
  198.  *  sasl_mutex_unlock unlocks mutex if it's locked
  199.  *   returns SASL_FAIL if not locked or parameter error
  200.  *   returns SASL_OK on success
  201.  */
  202. typedef void *sasl_mutex_new_t();
  203. typedef int sasl_mutex_lock_t(void *mutex);
  204. typedef int sasl_mutex_unlock_t(void *mutex);
  205. typedef void sasl_mutex_dispose_t(void *mutex);
  206.  
  207. LIBSASL_API void sasl_set_mutex(sasl_mutex_new_t *, sasl_mutex_lock_t *,
  208.                                 sasl_mutex_unlock_t *, sasl_mutex_dispose_t *);
  209.  
  210. /*****************************
  211.  * Security preference types *
  212.  *****************************/
  213.  
  214. /* security layer strength factor -- an unsigned integer usable by the caller
  215.  *  to specify approximate security layer strength desired.  Roughly
  216.  *  correlated to effective key length for encryption.
  217.  * 0   = no protection
  218.  * 1   = integrity protection only
  219.  * 40  = 40-bit DES or 40-bit RC2/RC4
  220.  * 56  = DES
  221.  * 112 = triple-DES
  222.  * 128 = 128-bit RC2/RC4/BLOWFISH
  223.  */
  224. typedef unsigned sasl_ssf_t;
  225.  
  226. /* secflags provided on sasl_server_new and sasl_client_new:
  227.  */
  228. #define SASL_SECURITY_LAYER (0x0001) /* caller supports security layer */
  229.  
  230. /***************************
  231.  * Security Property Types *
  232.  ***************************/
  233.  
  234. /* Structure specifying the client or server's security policy
  235.  * and optional additional properties.
  236.  */
  237.  
  238. /* These are the various security flags apps can specify. */
  239. /* NOPLAINTEXT          -- don't permit mechanisms susceptible to simple
  240.  *                         passive attack (e.g., PLAIN, LOGIN)
  241.  * NOACTIVE             -- protection from active (non-dictionary) attacks
  242.  *                         during authentication exchange.
  243.  *                Authenticates server.
  244.  * NODICTIONARY         -- don't permit mechanisms susceptible to passive
  245.  *                         dictionary attack
  246.  * FORWARD_SECRECY      -- require forward secrecy between sessions
  247.  *                         (breaking one won't help break next)
  248.  * NOANONYMOUS          -- don't permit mechanisms that allow anonymous login
  249.  * PASS_CREDENTIALS     -- require mechanisms which pass client
  250.  *               credentials, and allow mechanisms which can pass
  251.  *               credentials to do so
  252.  */
  253. #define SASL_SEC_NOPLAINTEXT     (0x0001)
  254. #define SASL_SEC_NOACTIVE        (0x0002)
  255. #define SASL_SEC_NODICTIONARY    (0x0004)
  256. #define SASL_SEC_FORWARD_SECRECY (0x0008)
  257. #define SASL_SEC_NOANONYMOUS     (0x0010)
  258. #define SASL_SEC_PASS_CREDENTIALS (0x0200)
  259.  
  260. typedef struct sasl_security_properties 
  261. {
  262.     /* security strength factor
  263.      *  min_ssf      = minimum acceptable final level
  264.      *  max_ssf      = maximum acceptable final level
  265.      */ 
  266.     sasl_ssf_t min_ssf;
  267.     sasl_ssf_t max_ssf;
  268.  
  269.     /* Maximum security layer receive buffer size.
  270.      *  0=security layer not supported
  271.      */
  272.     unsigned maxbufsize; 
  273.     
  274.     /* bitfield for security properties -- see SASL_SEC_* above */
  275.     int security_flags;
  276.  
  277.     /* NULL terminated array of additional property names, values */ 
  278.     const char **property_names;
  279.     const char **property_values;
  280. } sasl_security_properties_t; 
  281.  
  282.  
  283. /* Structure communicating the characteristics of an external security
  284.  * mechanism.  This is used with sasl_setprop() to inform the library
  285.  * of an active external security layer.  If the auth_id is non-NULL,
  286.  * this enables the EXTERNAL authentication mechanism; this may also
  287.  * allow other mechanisms to become active (for instance, if an
  288.  * application demands encryption, mechanisms which solely provide
  289.  * authentication might become active if the necessary encryption is
  290.  * provided external to SASL).  Since this potentially changes the
  291.  * list of supported mechanisms, the mechanism list should be re-sent,
  292.  * if it has been sent already.  */
  293. typedef struct sasl_external_properties
  294. {
  295.   /* security provided by the external mechanism */
  296.   sasl_ssf_t ssf;
  297.  
  298.   /* authorization identity provided by the external mechanism */
  299.   char *auth_id;
  300. } sasl_external_properties_t;
  301.  
  302. /******************
  303.  * Callback types *
  304.  ******************/
  305.  
  306. /* Extensible type for a client/server callbacks
  307.  *  id      -- identifies callback type
  308.  *  proc    -- procedure call arguments vary based on id
  309.  *  context -- context passed to procedure
  310.  */
  311. typedef struct sasl_callback {
  312.     /* Identifies the type of the callback function.
  313.      * Mechanisms must ignore callbacks with id's they don't recognize.
  314.      */
  315.     unsigned long id;
  316.     int (*proc)();  /* Callback function.  Types of arguments vary by 'id' */
  317.     void *context;
  318. } sasl_callback_t;
  319.  
  320. /* callback ids & functions:
  321.  */
  322. #define SASL_CB_LIST_END  (0) /* end of list */
  323.  
  324. /* option reading callback -- this allows a SASL configuration to be
  325.  *  encapsulated in the caller's configuration system.  Some implementations
  326.  *  may use default config file(s) if this is omitted.  Configuration items
  327.  *  may be plugin-specific and are arbitrary strings.
  328.  *
  329.  * inputs:
  330.  *  context     -- option context from callback record
  331.  *  plugin_name -- name of plugin (NULL = general SASL option)
  332.  *  option      -- name of option
  333.  * output:
  334.  *  result      -- set to result which persists until next getopt in
  335.  *                 same thread, unchanged if option not found
  336.  *  len         -- length of result (optional)
  337.  * returns:
  338.  *  SASL_OK     -- no error
  339.  *  SASL_FAIL   -- error
  340.  */
  341. typedef int sasl_getopt_t(void *context, const char *plugin_name,
  342.               const char *option,
  343.               const char **result, unsigned *len);
  344. #define SASL_CB_GETOPT      (1)
  345.  
  346. /* Logging levels for use with the logging callback function. */
  347. #define SASL_LOG_ERR        (1) /* error message */
  348. #define SASL_LOG_WARNING    (2) /* warning message */
  349. #define SASL_LOG_INFO       (3) /* normal message */
  350.  
  351. /* logging callback -- this allows plugins and the middleware to
  352.  *  log operations they perform.
  353.  * inputs:
  354.  *  context     -- logging context from the callback record
  355.  *  priority    -- logging priority; see above
  356.  *  message     -- message to log
  357.  * returns:
  358.  *  SASL_OK     -- no error
  359.  *  SASL_FAIL   -- error
  360.  */
  361. typedef int sasl_log_t(void *context,
  362.                int priority,
  363.                const char *message);
  364.  
  365. #define SASL_CB_LOG        (2)
  366.  
  367. /* getpath callback -- this allows applications to specify the
  368.  * colon-separated path to search for plugins (by default,
  369.  * taken from the SASL_PATH environment variable).
  370.  * inputs:
  371.  *  context     -- getpath context from the callback record
  372.  * outputs:
  373.  *  path    -- colon seperated path (allocated on the heap; the
  374.  *                 library will free it using the sasl_free_t *
  375.  *                 passed to sasl_set_callback, or the standard free()
  376.  *                 library call).
  377.  * returns:
  378.  *  SASL_OK     -- no error
  379.  *  SASL_FAIL   -- error
  380.  */
  381. typedef int sasl_getpath_t(void * context,
  382.                char ** path);
  383.  
  384. #define SASL_CB_GETPATH        (3)
  385.  
  386. /* verify file callback -- this allows applications to check if they
  387.  * want SASL to use files, file by file.  This is intended to allow
  388.  * applications to sanity check the environment to make sure plugins
  389.  * or the configuration file can't be written to, etc.
  390.  * inputs: 
  391.  *  context     -- verifypath context from the callback record
  392.  *  file        -- full path to file to verify
  393.  *  type        -- type of file to verify
  394.  
  395.  * returns:
  396.  *  SASL_OK        -- no error (file can safely be used)
  397.  *  SASL_CONTINUE  -- continue WITHOUT using this file
  398.  *  SASL_FAIL      -- error 
  399.  */
  400. typedef int sasl_verifyfile_t(void * context,
  401.                               const char * file, const int type);
  402.  
  403. #define SASL_CB_VERIFYFILE  (4)
  404.  
  405. /* these are the types of files libsasl will ask about */
  406. #define SASL_VRFY_PLUGIN    (1)
  407. #define SASL_VRFY_CONF        (2)
  408. #define SASL_VRFY_PASSWD    (3)
  409. #define SASL_VRFY_OTHER        (4)
  410.  
  411. /* client/user interaction callbacks:
  412.  */
  413. /* Simple prompt -- result must persist until next call to getsimple or
  414.  *  until connection context is disposed
  415.  * inputs:
  416.  *  context       -- context from callback structure
  417.  *  id            -- callback id
  418.  * outputs:
  419.  *  result        -- set to NUL terminated string
  420.  *                   NULL = user cancel
  421.  *  len           -- length of result, ignored with SASL_CB_SECRET
  422.  * returns SASL_OK
  423.  */
  424. typedef int sasl_getsimple_t(void *context, int id,
  425.                  const char **result, unsigned *len);
  426. #define SASL_CB_USER        (0x4001) /* client user identity to login as */
  427. #define SASL_CB_AUTHNAME    (0x4002) /* client authentication name,
  428.                           * defaults to authid in sasl_secret_t */
  429. #define SASL_CB_LANGUAGE    (0x4003) /* comma separated list of RFC 1766
  430.                           * language codes in order of preference
  431.                       * to be used to localize client prompts
  432.                       * or server error codes */
  433.  
  434. /* get a sasl_secret_t
  435.  *  psecret -- may be left NULL if sasl_client_auth() called
  436.  * returns SASL_OK
  437.  */
  438. typedef int sasl_getsecret_t(sasl_conn_t *conn, void *context, int id,
  439.                  sasl_secret_t **psecret);
  440. #define SASL_CB_PASS        (0x4004) /* client passphrase-based secret */
  441.  
  442.  
  443. /* prompt for input in response to a challenge, result is copied & erased
  444.  *  by caller.
  445.  * input:
  446.  *  context   -- context from callback structure
  447.  *  id        -- callback id
  448.  *  challenge -- server challenge
  449.  * output:
  450.  *  result    -- NUL terminated result, NULL = user cancel
  451.  *  len       -- length of result
  452.  * returns SASL_OK
  453.  */
  454. typedef int sasl_chalprompt_t(void *context, int id,
  455.                   const char *challenge,
  456.                   const char *prompt, const char *defresult,
  457.                   const char **result, unsigned *len);
  458. #define SASL_CB_ECHOPROMPT   (0x4005) /* challenge and client-entered result */
  459. #define SASL_CB_NOECHOPROMPT (0x4006) /* challenge and client-entered result */
  460.  
  461. /* prompt (or autoselect) the realm to do authentication in.
  462.  *  may get a list of valid realms.
  463.  * input:
  464.  *  context     -- context from callback structure
  465.  *  id          -- callback id
  466.  *  availrealms -- available realms; string list; NULL terminated
  467.  * output:
  468.  *  result      -- NUL terminated realm; NULL is equivalent to ""
  469.  * returns SASL_OK
  470.  * result must persist until the next callback
  471.  */
  472. /* If there is an interaction with SASL_CB_GETREALM the challenge of
  473.  *  the sasl_interact_t will be of the format: {realm1, realm2,
  474.  *  ...}. That is a list of possible realms seperated by comma spaces
  475.  *  enclosed by brackets. 
  476.  */
  477. typedef int sasl_getrealm_t(void *context, int id,
  478.                 const char **availrealms,
  479.                 const char **result);
  480. #define SASL_CB_GETREALM (0x4007) /* realm to attempt authentication in */
  481.  
  482.  
  483. /* server callbacks:
  484.  */
  485. /* callback to verify authorization
  486.  *  requested_user -- the identity/username to authorize
  487.  *  auth_identity  -- the identity associated with the secret
  488.  *                    if the identity is not in the realm specified in
  489.  *                    sasl_server_new, it will be of the form user@realm
  490.  * return:
  491.  *  user           -- NULL = requested_user, otherwise canonicalized
  492.  *  errstr         -- can be set to error string on failure
  493.  * returns SASL_OK on success, SASL_BADAUTH or other SASL response on failure
  494.  */
  495. typedef int sasl_authorize_t(void *context,
  496.                  const char *auth_identity,
  497.                  const char *requested_user,
  498.                  const char **user,
  499.                  const char **errstr);
  500. #define SASL_CB_PROXY_POLICY (0x8001)
  501.  
  502. /* callback to lookup a user's secret for a mechanism
  503.  *  mechanism     -- the mechanism requesting its secret
  504.  *  auth_identity -- the identity being looked up
  505.  *  realm         -- the realm the identity is in
  506.  * return:
  507.  *  secret        -- the secret associated with this user
  508.  *                   for this mechanism
  509.  * returns SASL_OK on success or other SASL response on failure
  510.  */
  511. typedef int sasl_server_getsecret_t(void *context,
  512.                     const char *mechanism,
  513.                     const char *auth_identity,
  514.                     const char *realm,
  515.                     sasl_secret_t ** secret);
  516. #define SASL_CB_SERVER_GETSECRET (0x8002)
  517.  
  518. /* callback to store a user's secret for a mechanism
  519.  *  mechanism     -- the mechanism storing its secret
  520.  *  auth_identity -- the identity being stored
  521.  *  realm         -- the realm the identity is in
  522.  *  secret        -- the secret associated with this user
  523.  *                   for this mechanism.  If NULL, user's secret
  524.  *             for this mechanism will be erased.
  525.  * returns SASL_OK on success or other SASL response on failure
  526.  */
  527. typedef int sasl_server_putsecret_t(void *context,
  528.                     const char *mechanism,
  529.                     const char *auth_identity,
  530.                     const char *realm,
  531.                     const sasl_secret_t * secret);
  532. #define SASL_CB_SERVER_PUTSECRET (0x8003)
  533.  
  534.  
  535. /**********************************
  536.  * Common Client/server functions *
  537.  **********************************/
  538.  
  539. /* dispose of all SASL plugins.  Connection
  540.  * states have to be disposed of before calling this.
  541.  */
  542. LIBSASL_API void sasl_done(void);
  543.  
  544. /* dispose connection state, sets it to NULL
  545.  *  checks for pointer to NULL
  546.  */
  547. LIBSASL_API void sasl_dispose(sasl_conn_t **pconn);
  548.  
  549. /* translate server error code to user error code
  550.  *  currently only maps SASL_NOUSER to SASL_BADAUTH
  551.  */
  552. LIBSASL_API int sasl_usererr(int saslerr);
  553.  
  554. /* translate an error number into a string
  555.  * input:
  556.  *  saslerr  -- the error number
  557.  *  langlist -- comma separated list of RFC 1766 languages (may be NULL)
  558.  * results:
  559.  *  outlang  -- the language actually used (may be NULL if don't care)
  560.  * returns:
  561.  *  the error message
  562.  */
  563. LIBSASL_API const char *sasl_errstring(int saslerr,
  564.                const char *langlist,
  565.                const char **outlang);
  566.                
  567. /* get property from SASL connection state
  568.  *  propnum       -- property number
  569.  *  pvalue        -- pointer to value
  570.  * returns:
  571.  *  SASL_OK       -- no error
  572.  *  SASL_NOTDONE  -- property not available yet
  573.  *  SASL_BADPARAM -- bad property number
  574.  */
  575. LIBSASL_API int sasl_getprop(sasl_conn_t *conn, int propnum, void **pvalue);
  576. #define SASL_USERNAME   0     /* pointer to NUL terminated user name */
  577. #define SASL_SSF        1     /* security layer security strength factor,
  578.                    * if 0, call to sasl_encode, sasl_decode
  579.                    * unnecessary */
  580. #define SASL_MAXOUTBUF  2     /* security layer max output buf unsigned */  
  581. #define SASL_REALM      3     /* server authentication realm used */
  582. #define SASL_GETOPTCTX  4     /* context for getopt callback */
  583. #define SASL_IP_LOCAL   5     /* local address (pvalue=sockaddr_in *) */
  584. #define SASL_IP_REMOTE  6     /* remote address (pvalue=sockaddr_in *) */
  585.  
  586. /* set property in SASL connection state
  587.  * returns:
  588.  *  SASL_OK       -- value set
  589.  *  SASL_BADPARAM -- invalid property or value
  590.  */
  591. LIBSASL_API int sasl_setprop(sasl_conn_t *conn,
  592.                  int propnum,
  593.                  const void *value);
  594. #define SASL_SSF_EXTERNAL 100  /* external SSF active --
  595.                 * sasl_external_properties_t */
  596. #define SASL_SEC_PROPS    101  /* sasl_security_properties_t */
  597.                    /* also allows SASL_IP_LOCAL, SASL_IP_REMOTE */
  598.  
  599. /* do precalculations during an idle period or network round trip
  600.  *  may pass NULL to precompute for some mechanisms prior to connect
  601.  *  returns 1 if action taken, 0 if no action taken
  602.  */
  603. LIBSASL_API int sasl_idle(sasl_conn_t *conn);
  604.  
  605. /**************
  606.  * Client API *
  607.  **************/
  608.  
  609. /* list of client interactions with user for caller to fill in
  610.  */
  611. typedef struct sasl_interact {
  612.     unsigned long id;        /* same as client/user callback ID */
  613.     const char *challenge;      /* may be computer readable */
  614.     const char *prompt;         /* always human readable */
  615.     const char *defresult;    /* default result string */
  616.     void *result;        /* set to point to result -- this will 
  617.                  * be freed by the library iff it
  618.                  * would be freed by the library if
  619.                  * returned from normal callback of
  620.                  * the same id */
  621.     unsigned len;        /* set to length of result */
  622. } sasl_interact_t;
  623.  
  624. /* initialize the SASL client drivers
  625.  *  callbacks      -- base callbacks for all client connections
  626.  * returns:
  627.  *  SASL_OK        -- Success
  628.  *  SASL_NOMEM     -- Not enough memory
  629.  *  SASL_BADVERS   -- Mechanism version mismatch
  630.  *  SASL_BADPARAM  -- error in config file
  631.  *  SASL_NOMECH    -- No mechanisms available
  632.  *  ...
  633.  */
  634. LIBSASL_API int sasl_client_init(const sasl_callback_t *callbacks);
  635.  
  636. /* initialize a client exchange based on the specified mechanism
  637.  *  service       -- registered name of the service using SASL (e.g. "imap")
  638.  *  serverFQDN    -- the fully qualified domain name of the server
  639.  *  prompt_supp   -- list of client interactions supported
  640.  *                   may also include sasl_getopt_t context & call
  641.  *                   NULL prompt_supp = user/pass via SASL_INTERACT only
  642.  *                   NULL proc = interaction supported via SASL_INTERACT
  643.  *  secflags      -- security flags (see above)
  644.  * in/out:
  645.  *  pconn         -- connection negotiation structure
  646.  *                   pointer to NULL => allocate new
  647.  *                   non-NULL => recycle storage and go for next available mech
  648.  *
  649.  * Returns:
  650.  *  SASL_OK       -- success
  651.  *  SASL_NOMECH   -- no mechanism meets requested properties
  652.  *  SASL_NOMEM    -- not enough memory
  653.  */
  654. LIBSASL_API int sasl_client_new(const char *service,
  655.             const char *serverFQDN,
  656.             const sasl_callback_t *prompt_supp,
  657.             int secflags,
  658.             sasl_conn_t **pconn);
  659.  
  660. /* select a mechanism for a connection
  661.  *  mechlist      -- mechanisms server has available (punctuation ignored)
  662.  *  secret        -- optional secret from previous session
  663.  * output:
  664.  *  prompt_need   -- on SASL_INTERACT, list of prompts needed to continue
  665.  *  clientout     -- the initial client response to send to the server
  666.  *  mech          -- set to mechanism name
  667.  *
  668.  * Returns:
  669.  *  SASL_OK       -- success
  670.  *  SASL_NOMEM    -- not enough memory
  671.  *  SASL_NOMECH   -- no mechanism meets requested properties
  672.  *  SASL_INTERACT -- user interaction needed to fill in prompt_need list
  673.  */
  674. LIBSASL_API int sasl_client_start(sasl_conn_t *conn,
  675.                   const char *mechlist,
  676.                   sasl_secret_t *secret,
  677.                   sasl_interact_t **prompt_need,
  678.                   char **clientout,
  679.                   unsigned *clientoutlen,
  680.                   const char **mech);
  681.  
  682. /* do a single authentication step.
  683.  *  serverin    -- the server message received by the client, MUST have a NUL
  684.  *                 sentinel, not counted by serverinlen
  685.  * output:
  686.  *  prompt_need -- on SASL_INTERACT, list of prompts needed to continue
  687.  *  clientout   -- the client response to send to the server
  688.  *
  689.  * returns:
  690.  *  SASL_OK        -- success
  691.  *  SASL_INTERACT  -- user interaction needed to fill in prompt_need list
  692.  *  SASL_BADPROT   -- server protocol incorrect/cancelled
  693.  *  SASL_BADSERV   -- server failed mutual auth
  694.  */
  695. LIBSASL_API int
  696. sasl_client_step(sasl_conn_t *conn,
  697.          const char *serverin,
  698.          unsigned serverinlen,
  699.          sasl_interact_t **prompt_need,
  700.          char **clientout,
  701.          unsigned *clientoutlen);
  702.  
  703. /* Set connection secret based on passphrase
  704.  *  may be used in SASL_CB_PASS callback
  705.  * input:
  706.  *  user          -- username
  707.  *  pass          -- plaintext passphrase with NUL sentinel
  708.  *  passlen       -- 0 = strlen(pass)
  709.  * out:
  710.  *  prompts       -- if non-NULL, SASL_CB_PASS item filled in
  711.  *  keepcopy      -- set to copy of secret if non-NULL
  712.  * returns:
  713.  *  SASL_OK       -- success
  714.  *  SASL_NOMEM    -- failure
  715.  */
  716. LIBSASL_API int
  717. sasl_client_auth(sasl_conn_t *conn,
  718.          const char *user,
  719.          const char *pass, unsigned passlen,
  720.          sasl_interact_t *prompts, sasl_secret_t **keepcopy);
  721.  
  722. /* erase & dispose of a sasl_secret_t
  723.  *  calls free utility last set by sasl_set_alloc
  724.  */
  725. LIBSASL_API void sasl_free_secret(sasl_secret_t **);
  726.  
  727. /**************
  728.  * Server API *
  729.  **************/
  730.  
  731. /* initialize server drivers, done once per process
  732.  *  callbacks      -- base callbacks for all server connections
  733.  *  appname        -- name of calling application (for lower level logging)
  734.  * results:
  735.  *  state          -- server state
  736.  * returns:
  737.  *  SASL_OK        -- success
  738.  *  SASL_BADPARAM  -- error in config file
  739.  *  SASL_NOMEM     -- memory failure
  740.  *  SASL_BADVERS   -- Mechanism version mismatch
  741.  */
  742. LIBSASL_API int sasl_server_init(const sasl_callback_t *callbacks,
  743.                  const char *appname);
  744.  
  745.  
  746. /* create context for a single SASL connection
  747.  *  service        -- registered name of the service using SASL (e.g. "imap")
  748.  *  serverFQDN     -- Fully qualified server domain name.  NULL means use
  749.  *                    gethostname().  Useful for multi-homed servers.
  750.  *  user_realm     -- permits multiple user domains on server, NULL = default
  751.  *  callbacks      -- callbacks (e.g., authorization, lang, new getopt context)
  752.  *  secflags       -- security flags (see above)
  753.  * returns:
  754.  *  pconn          -- new connection context
  755.  *
  756.  * returns:
  757.  *  SASL_OK        -- success
  758.  *  SASL_NOMEM     -- not enough memory
  759.  */
  760. LIBSASL_API int sasl_server_new(const char *service,
  761.                 const char *serverFQDN,
  762.                 const char *user_realm,
  763.                 const sasl_callback_t *callbacks,
  764.                 int secflags,
  765.                 sasl_conn_t **pconn);
  766.  
  767. /* This returns a list of mechanisms in a NUL-terminated string
  768.  *  user          -- restricts mechanisms to those available to that user
  769.  *                   (may be NULL)
  770.  *  prefix        -- appended to beginning of result
  771.  *  sep           -- appended between mechanisms
  772.  *  suffix        -- appended to end of result
  773.  * results:
  774.  *  result        -- NUL terminated allocated result, caller must free
  775.  *  plen          -- gets length of result (excluding NUL), may be NULL
  776.  *  pcount        -- gets number of mechanisms, may be NULL
  777.  *
  778.  * returns:
  779.  *  SASL_OK        -- success
  780.  *  SASL_NOMEM     -- not enough memory
  781.  *  SASL_NOMECH    -- no enabled mechanisms
  782.  */
  783. LIBSASL_API int sasl_listmech(sasl_conn_t *conn,
  784.                   const char *user,
  785.                   const char *prefix,
  786.                   const char *sep,
  787.                   const char *suffix,
  788.                   char **result,
  789.                   unsigned *plen,
  790.                   unsigned *pcount);
  791.  
  792. /* start a mechanism exchange within a connection context
  793.  *  mech           -- the mechanism name client requested
  794.  *  clientin       -- client initial response, NULL if empty
  795.  *  clientinlen    -- length of initial response
  796.  *  serverout      -- initial server challenge, NULL if done
  797.  *  serveroutlen   -- length of initial server challenge
  798.  * output:
  799.  *  pconn          -- the connection negotiation state on success
  800.  *  errstr         -- set to string to send to user on failure
  801.  *
  802.  * Same returns as sasl_server_step()
  803.  */
  804. LIBSASL_API int sasl_server_start(sasl_conn_t *conn,
  805.                   const char *mech,
  806.                   const char *clientin,
  807.                   unsigned clientinlen,
  808.                   char **serverout,
  809.                   unsigned *serveroutlen,
  810.                   const char **errstr);
  811.  
  812. /* perform one step of the SASL exchange
  813.  *  inputlen & input -- client data
  814.  *                      NULL on first step if no optional client step
  815.  *  outputlen & output -- set to the server data to transmit
  816.  *                        to the client in the next step
  817.  *  errstr           -- set to a more text error message from
  818.  *                    a lower level mechanism on failure
  819.  *
  820.  * returns:
  821.  *  SASL_OK        -- exchange is complete.
  822.  *  SASL_CONTINUE  -- indicates another step is necessary.
  823.  *  SASL_TRANS     -- entry for user exists, but not for mechanism
  824.  *                    and transition is possible
  825.  *  SASL_BADPARAM  -- service name needed
  826.  *  SASL_BADPROT   -- invalid input from client
  827.  *  ...
  828.  */
  829. LIBSASL_API int sasl_server_step(sasl_conn_t *conn,
  830.              const char *clientin,
  831.              unsigned clientinlen,
  832.              char **serverout,
  833.              unsigned *serveroutlen,
  834.              const char **errstr);
  835.  
  836. /* check if a plaintext password is valid
  837.  * if user is NULL, check if plaintext is enabled
  838.  * inputs:
  839.  *  user         -- user to query in current user_realm
  840.  *  userlen      -- length of username, 0 = strlen(user)
  841.  *  pass         -- plaintext password to check
  842.  *  passlen      -- length of password, 0 = strlen(pass)
  843.  * outputs:
  844.  *  errstr       -- set to error message for use in protocols
  845.  * returns 
  846.  *  SASL_OK      -- success
  847.  *  SASL_NOMECH  -- user found, but no verifier
  848.  *  SASL_NOUSER  -- user not found
  849.  */
  850. LIBSASL_API int sasl_checkpass(sasl_conn_t *conn,
  851.                    const char *user,
  852.                    unsigned userlen,
  853.                    const char *pass,
  854.                    unsigned passlen,
  855.                    const char **errstr);
  856.  
  857. /* check if a user exists on server
  858.  *  service       -- registered name of the service using SASL (e.g. "imap")
  859.  *  user_realm    -- permits multiple user domains on server, NULL = default
  860.  *  user          -- NUL terminated user name
  861.  *
  862.  * returns:
  863.  *  SASL_OK       -- success
  864.  *  SASL_DISABLED -- account disabled
  865.  *  SASL_NOUSER   -- user not found
  866.  *  SASL_NOMECH   -- user found, but no usable mechanism
  867.  */
  868. LIBSASL_API int sasl_user_exists(const char *service,
  869.              const char *user_realm,
  870.              const char *user);
  871.  
  872. /* set the password for a user
  873.  *  conn        -- SASL connection
  874.  *  user        -- user name
  875.  *  pass        -- plaintext password, may be NULL to remove user
  876.  *  passlen     -- length of password, 0 = strlen(pass)
  877.  *  flags       -- see flags below
  878.  *  errstr      -- optional more detailed error
  879.  * 
  880.  * returns:
  881.  *  SASL_NOCHANGE  -- proper entry already exists
  882.  *  SASL_NOMECH    -- no authdb supports password setting as configured
  883.  *  SASL_DISABLED  -- account disabled
  884.  *  SASL_PWLOCK    -- password locked
  885.  *  SASL_FAIL      -- OS error
  886.  *  SASL_BADPARAM  -- password too long
  887.  *  SASL_OK        -- successful
  888.  */
  889. LIBSASL_API int sasl_setpass(sasl_conn_t *conn,
  890.          const char *user,
  891.          const char *pass,
  892.          unsigned passlen,
  893.          int flags,
  894.          const char **errstr);
  895. #define SASL_SET_CREATE  0x01   /* create a new entry for user */
  896. #define SASL_SET_DISABLE 0x02    /* disable user account */
  897.  
  898. /**********************
  899.  * security layer API *
  900.  **********************/
  901.  
  902. /* encode a block of data for transmission using security layer
  903.  * returns:
  904.  *  SASL_OK      -- success (returns input if no layer negotiated)
  905.  *  SASL_NOTDONE -- security layer negotiation not finished
  906.  */
  907. LIBSASL_API int sasl_encode(sasl_conn_t *conn,
  908.                 const char *input, unsigned inputlen,
  909.                 char **output, unsigned *outputlen);
  910.  
  911. /* decode a block of data received using security layer
  912.  * returns:
  913.  *  SASL_OK      -- success (returns input if no layer negotiated)
  914.  *  SASL_NOTDONE -- security layer negotiation not finished
  915.  */
  916. LIBSASL_API int sasl_decode(sasl_conn_t *conn,
  917.                 const char *input, unsigned inputlen,
  918.                 char **output, unsigned *outputlen);
  919.  
  920. /************************************
  921.  * Credentials API (used by server) *
  922.  ************************************/
  923.  
  924. /* install credentials passed by the client
  925.  * Installing a set of credentials may install them on a per-process
  926.  * or a per-thread basis; neither behavior may be assumed.
  927.  * returns:
  928.  *  SASL_OK      -- success
  929.  *  SASL_FAIL    -- failure
  930.  *  SASL_NOTDONE -- credentials not passed
  931.  */
  932. LIBSASL_API int sasl_cred_install(sasl_conn_t *conn);
  933.  
  934. /* uninstalls a connection's credentials
  935.  * returns:
  936.  *  SASL_OK      -- success
  937.  *  SASL_FAIL    -- failure
  938.  */
  939. LIBSASL_API int sasl_cred_uninstall(sasl_conn_t *conn);
  940. #endif /* SASL_H */
  941.  
  942.